[% setvar title Function-call named parameters (with compiler optimizations) %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Function-call named parameters (with compiler optimizations)</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Michael Maraist &lt;<a href='mailto:maraist@udel.edu'>maraist@udel.edu</a>&gt;
  Date: 25 Aug 2000
  Last Modified: 30 Sep 2000
  Mailing List: <a href='mailto:perl6-language-subs@perl.org'>perl6-language-subs@perl.org</a>
  Number: 160
  Version: 3
  Status: Frozen</pre>
<a name='CHANGES'></a><h1>CHANGES</h1>
<p>Finialized various features by removing many of the options( grealy
simplified the RFC).  Unified the goals with that of RFC 176 and RFC 273.</p>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Function parameters and their positions can be ambiguous in
function-oriented programming.  Hashes offer tremendous help in this
realm, except that error checking can be very tedious. Also, hashes,
in general, take a performance hit.</p>
<p>The goal is to enhance functionality / convinience / performance where
possible in regards to named-parameters, with a minimal of changes.
And, at the same time, allow this to be a completely optional and
virtually transparent process.  The following is an in-depth analysis
of various ways of accomplishing these goals.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>The current method of parameter proto-types only fulfills a tiny
niche, which is mainly to offer compile-type checking and to
disambiguate context ( as in sub foo($) { }, or sub foo(&amp;$) { } ).
No support, however, is given to hashes, even though they are one of
perl's greatest strengths.  We see them pop up in parameterized
function calls all over the place (CGI, tk, SQL wrapper functions,
etc).  As above, however, it is left to the coder to check the
existance of required parameters, since in this realm, the current
proto-types are of no help.  It should not be much additional work to
provide an extension to prototypes that allow the definition of
hashes.</p>
<p>The following is a complex example of robust code:</p>
<pre> #/usr/bin/perl -w
 use strict

 # IN: hash:
 #         a =&gt; '...' # req
 #         b =&gt; '...' # req, defined
 #         c =&gt; '...' # req, 0 &lt;= c &lt;= MAX_C
 #         d =&gt; '..'  # opt
 #         e =&gt; '..'  # opt
 #         f =&gt; '..'   # opt
 # OUT: xxx
 sub foo {
  my $self = shift;
  my %args = @_;

  # Requires $a
  my $a;
  die &quot;No a provided&quot;
     unless exists $args{a};
  $a = $args{a};

  # Requires non-null $b
  my $b;
  die &quot;invalid b&quot;
     unless exists $args{b} &amp;&amp; defined ($b = $args{b});

  #  Requires non-null and bounded $c
  my $c;
  die &quot;Invalid c&quot;
     unless exists $args{c} &amp;&amp; defined ($b = $args{b}) &amp;&amp; ($c &gt;= 0 &amp;&amp; $c &lt;
$MAX_C);

  my ( $d, $e, $f ) = @args{ qw( d e f ) };
  ...
 } # end foo</pre>
<p>Becomes:</p>
<pre> sub foo($%) : method required_fields(a b c) fields(d e f) doc(&lt;&lt;EOS) {
 # IN: hash:
 #         a =&gt; '...' # req;  Do some A
 #         b =&gt; '...' # req, defined; Do some B
 #         c =&gt; '...' # req, 0 &lt;= c &lt;= MAX_C; Do some C
 #         d =&gt; '..'  # opt; Do some D
 #         e =&gt; '..'  # opt; Do some E
 #         f =&gt; '..'   # opt; Do some F
 # OUT: xxx
 EOS
   my $self = shift;
   my %args : fields(a b c d e f) = @_; # produce optimized hash
    that is already pre-allocated at compile-time.

   # Requires non-null $args{b}
   die &quot;invalid b&quot;
      unless defined $args{b};

   # Requires non-null and bounded $args{c}
   die &quot;invalid c&quot;
      unless defined $args{c} &amp;&amp; ($args{c} &gt;= 0 &amp;&amp; $args{c} &lt; $MAX_C);

   ...
 } # end foo

 $obj-&gt;foo( c =&gt; 3, b =&gt; 2, f=&gt; 8, a =&gt; 1 );
 # Note the out-of order, and the mixture of optional fields

 foo( $obj, a =&gt; 1, b =&gt; 2, c =&gt; 3 ); # still totally legal
 foo( a =&gt; 1, b =&gt; 2 ); # compiler-error (invalid num-args)
 foo( 1,2,3,4,5,6,7); # compiler-error, missing args a, b and c
 foo(a,1,b,2,c,3,$obj); # compiler-error, missing args a, b and c
 # (since they're offset by one)
 my @args = ( a =&gt; 1, b =&gt; 2, c =&gt; 3);
 $obj-&gt;foo( @args ); # checking-deffered to run-time.  Will be ok.
 my @bad_args = ( b =&gt; 8, e =&gt; 4 );
 $obj-&gt;foo( @bad_args ); # checking-deffered to run-time.  Will fail.</pre>
<p>Essentially, perl's compiler can be put to use for hashed-function
calls in much the same way as pseudo hashes work for structs/objects.
Making this a compile-time check would drastically reduce run-time errors
in code (that used hash-based parameters).  It would also make the code
both more readible AND more efficient.</p>
<p>For readibility, perl can be quiried for the list of allowable options as well
as general documentation.  In the above, the listing of Input options would
have been redundant, for both the code-reader, and the run-time query, but was
provided for completeness.</p>
<p>Note also that the above is compatible with the existing structure.  In fact,
foo required the old-style prototype to distinguish the &quot;self&quot; variable from
the general-hash arguments.  The use of the attribute &quot;method&quot; was optional,
and could be used in the auto-generation of a $SELF variable.  At the very
least, it allows a run-time description of what the first argument really-is.</p>
<p>An important thing to note is that we're not changing the functionality of
execution.  Perl sub's still look and feel like old-style subs to the user.
They simply act as if additional run-time checking has occured.  The only
physical difference is that, where possible, you will find compile-time errors.</p>
<p>In the case that a static parameter list is provided (no dynamically expanded
array's / hashes), and the strict-hash method is used (see RFC 273), then a
compile-time reordering can occur, which has the effect of an array copy of
values instead of the generation of a hash.  So long as the subroutine never
makes use of dynamic field lookup, a hash is never used (except for a
behind-the-schenes mapping of dynamic parameters).</p>
<p>This helps large-scale functions, such as TK / CGI / etc, where there are
dozens of optional parameters that should all be called explicitly in the code.</p>
<p>Proposed attributes for subroutines are as follows:</p>
<ul>
<li><a name='locked'></a>locked</li>
<p>In multi threading, locks the function unless is also declared as a
method, in which the object is instead locked.</p>
<li><a name='method'></a>method</li>
<p>Compatibility, used in conjunction with 'lock' to perform object locking in
multi-threading.  Also allows enhanced documentation and description of the
first argument.</p>
<li><a name='fields( keyA keyB keyC ... )'></a>fields( keyA keyB keyC ... )</li>
<p>Describes the pseudo-hash / strict-hash allowable parameters (in conjunction
with other attributes).  Hash keys that do not match this list will generate
errors (at compile time if function-calls are static lists, or at run-time, if
expanded array's/ hashes are used).  The advantage of this approach over using
qs-structures or through redefinition of proto-types (as in &quot;sub foo($a, $b,
$c) {&quot;) is that we maintain back-ward compatibility, by providing a logical
SUPERSET of attribute information on subroutine.  This superset can
additionally be extended (as in the use of required_fields).  It also allows
the field list to be visible at the prototype.</p>
<p>key-names may have an optional data-type prefix, such as $, %, %, &amp;, * that
enforce the data-type at compile/runtime.  They would not be part of the
key-name.</p>
<li><a name='required_fields( keyA keyB keyC )'></a>required_fields( keyA keyB keyC )</li>
<p>Works in conjunction with fields to define the list of allowable set of hash
keys.  This set defines required fields while the &quot;fields&quot; set defines optional
ones.  To reduce confusion, and errors, these two sets may over-lap.  The total
list of optional fields is the union of all field-defining attributes.</p>
<p>key-names could have prefixes as in &quot;fields&quot; above.</p>
</ul>
<p>As above, The allowable fields is the union of fields(..) and
required_fields(...).  The text representing &quot;...&quot; is treated just like qw(...)
as would be use vars qw(...).  This method allows extensions that could more
finely define data-types.  For example, it is possible (though not currently
proposed) that these attribute lists could do the following:</p>
<pre> sub foo : required_fields( $cnt @list %data ) {
   my %args: fields(cnt list data) = @_;
   print &quot;Cnt = $args{cnt}\n&quot;;   # cnt garunteed to be a scalar
   for my $item ( @{$args{list}} ) { ... } # list garunteed to be an array ref
   while( my ( $key, $val ) = %{$args{data}} ) { ... }
     # data garunteed to be a hash-ref
 }

 my %data = ( a =&gt; 1, b =&gt; 2 );
 foo( cnt =&gt; 5, list =&gt; [ 1, 2, 3 ], data =&gt; \%data );</pre>
<p>The lack of any prefix would mean that any data-type would be allowable.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>The compilation and run-time code would have to be augmented to handle the
restrictive field-attributes.</p>
<ul>
<li><a name='Compile Time'></a>Compile Time</li>
<p>When a new sub statement is detected with fields or required_fields, a
strict-hash structure will have to be internally defined for it (see RFC 273
for details).  If perl is not in strict mode, then it's possible that lazy
execution of functions may have been compiled prior to reading the proto-type.
In the interests of efficiency, they will simply have to be deferred to
run-time checking (through the setting of flags).</p>
<p>For all subsequent invocations of the subroutine, traditional proto-type
checking will be augmented with parameter-checking so long as no expansions of
array's / hashes are detected.  This will involve checking the existence of
key-names.</p>
<p>If data-type checking is implemented (in perl), and the subroutine has elected
to use it, then static values (of the parameter hash) will be checked for
proper data-types.  Any use of variables as values (which is often the case)
will defer additional checking to run-time.</p>
<p>The subroutine-call will be flagged as having been compiler-checked for
parameter presence, and optionally data-type correctness.  In order to
alleviate complexity, if data-type correctness is required, and _any_
parameters are dynamic, then the sub-call will be flagged for run-time
data-type-correctness-checking.</p>
<p>Optionally, the compilation stage may try and detect usage of a strict-hash for
the hash-parameters.  As in:</p>
<pre> sub foo($$$%) : required_fields(a b) {
  my ( $a, $b, $c );
  my %hash : fields(a b);
  ( $a, $b, $c, %hash ) = @_;
  ...
 }</pre>
<p>In this case, it might be possible to optimize the last 4 array possitions of
@_ in such a way that the hash assignment at the very least by-passes
additional run-time checking of fields, and at the most, performs a direct
array-copy of data as in:</p>
<pre>  my %hash : fields(a b);
  if ( COMPILER_OPTIMIZED &amp;&amp; NO_DYNAMIC_FIELDS ) {
   @hash{qw(a b)} = $_[4, 5]; #which internally is @hash[0, 1] = $_[4, 5]
  } else {
   %hash = @_[ 3 .. $#_ ];
  }</pre>
<p>This assumes that the sub-call was optimized by re-ordering the fields.
Obviously this can only work on required_fields.  Additionally, reordering of
fields would be expensive in a run-time environment.  Additionally, this adds
complexity when dealing with shift's of @_, but this can all be determined at
compile-time.  Again, this is an optimization and thus optional.</p>
<li><a name='Run Time'></a>Run Time</li>
<p>Once a subroutine is called, it's arguments are expanded and placed on the call
stack as has occured historically.  Part of those arguments is a hidden field
that describes how much compile-time optimization has occured.  This may take
the form of a different type of sub-call op-code (ideal case), or in the form
of a hidden stack-parameter.  In either case, several things are checked for.</p>
<p>If the call was optimized into an array, then no additional computation will
occur, @_ will be passed as is.  One possible optimization at this point would
be to assign the trailing hash-parameters to the strict-args-hash directly as
above (since the strict hash is really an array with hash-like-access).  This
is the ideal case.</p>
<p>If dynamic values were used in the called hash, perl will have to internally
check the data-types for validity if requested (this could be expensive, but if
the user really needed it, they'd have to do it in even more expensive
perl-code).  I suggest that we should not punish good programming practices by
adding extra typing or massive performance penalties.</p>
<p>If the key-names were dynamically expanded, then perl will internally check
key-names for the set of required and allowable.  The above check for
value-data-types is then optionally performed.</p>
</ul>
<a name='SUMMARY'></a><h1>SUMMARY</h1>
<p>In summary, in keeping with perl's spirit, we should definately not
enforce a new function / method invocation process; not even for
hash-based / named parameters.  Also, it makes little sence to produce
an entirely new syntax for one or two special cases, which only obtain
performance benifits under certain conditions.  This would needlessly
produce legacy code which would be difficult to maintain in the
future.</p>
<p>This RFC suggests a compatible method of named-parameters through the use of an
optional compiler-level hash.  Initial implementations could all be applied as
a form of pre-processor.  Subsequent versions could internally optimize various
special cases.  The use of attributes is a logical extension, since we first
define the core of an entity, then extend the description for the purposes of
optimization and narrowing of correctness of code.</p>
<p>This RFC made heavy reference to the proposed built-in-pseudo-hash or
strict-hash described in RFC 273, but the beauty is that that just about
everything is independant and thus optional.  The following is the minimum
defined by this RFC:</p>
<pre> sub foo : fields( a b c) {
  # uses @_ just as before
 }

 foo( @args ); # so long as args defines the hash ( a=&gt; 1, b =&gt; 2, c =&gt; 3 )</pre>
<p>The following is the ideal case (allows all possible optimizations:</p>
<pre> sub foo($%) : fields( $a %b @c ) required_fields( $a ) doc(&quot;useful stuff&quot;)
{
   # uses @_ just as before
   my $scalar = shift;
   my %args : fields ( a b c ) = @_;
 }

 foo( $scalar, a =&gt; 5, b =&gt; { .. }, c =&gt; [.. ] );</pre>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>Thread</p>
<p>man perlref: pseudo-hashes</p>
<p>RFC 273: Internal representation of Pseudo-hashes using attributes.</p>
<p>RFC 176: subroutine / generic entity documentation</p>
<p>RFC 57: Subroutine prototypes and parameters</p>
<p>RFC 75: structures and interface definitions</p>
<p>RFC 152: Replace invocant in @_ with self() builtin</p>
</div>
